Container: a reset keeps the sort pending for the children it keeps - #1836

Description

Adding a child to a container appends it and queues a sort for the next tick. Container#reset() cancelled that sort (in clearChildren), then removed every child that is not persistent. The persistent children it kept therefore stayed in the order they were added, their depth ignored, until something else sorted the container.

The usual way to get there: a screen adds its persistent objects and loads a level straight away. level.load resets the world, so the screen's own objects were never sorted:

world.addChild(sky, -10);   // persistent
world.addChild(board, 0);   // persistent, the level goes in here
world.addChild(hud, 10);    // persistent
await level.load("map", { container: board, async: true });
// before: sky drawn over the board and the HUD

It showed up in the Starsweep example as a screen with nothing but the background on it. The example works around it with a world.sort() after each load.

Fix

• reset() notes whether a sort was pending and, if any children remain after clearing, sorts again (the same deferred sort() that addChild queues).
• destroy() is untouched. It calls clearChildren directly, so nothing is queued against a destroyed container, which is the problem the clearChildren split was made to avoid.

Also:

• Changelog: a Fixed entry.
• Skills: a symptom row in the Tiled skill, with the workaround for older versions.

Type of change

• Bug fix
• New feature
• Documentation update
• Performance improvement
• Refactoring (no functional changes)

Checklist

• I have read the Contributing Guide
• My code follows the existing code style (pnpm lint passes): Biome and tsc clean, no new ESLint warnings
• I have tested my changes locally (pnpm test passes): full engine suite, 379 files / 9624 tests pass
• I have added tests that cover my changes (if applicable): tests/container-reset-sort.spec.js. The reset() case and the level.load case fail without the fix (sky on top) and pass with it. Three more pin that no sort is queued when none was pending, when no children remain, or on destroy().
• The build succeeds (pnpm build): left to CI

Related issues

None.

Generated by Claude Code